Placement of Tab for valGraphics Documentation 


The tab title included should be inserted into the tab: 
* valGRAPHICS Locate before section XL I 


Documentation for the Floating Point Extensions is at the end of 
this package. Its pages are numbered for integration into the 
floating point documentation in the valFORTH 1.1 package. 
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Many different approaches to creating "computer graphics" are possible, and, 
indeed, many have been implemented. One of the most fruitful approaches, parti¬ 
cularly for two-dimensional graphics work, is a system usually called "turtle 
graphics." The valGraphics package is a turtle-like system patterned after the 
ATARI PILOT turtle graphics rendition, though with many significant extensions. 
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Overview 


Turtle geometry was originally developed at MIT by Dr. Seymour 
Papert and the LOGO group there. Since that time, a variety of 
different computer-based applications have been said to support 
"turtle graphics," though in general they differ in various ways 
from the initial LOGO formulation. The formulation adopted for this 
package follows the ATARI PILOT turtle graphics nomenclature where 
possible. In general, commands in this package are much smarter than 
their PILOT counterparts, but have also been made friendly so that in 
their default modes they are functionally similar to PILOT commands. 
Because this package differs from "true" turtle graphics in many ways, 
it is called "armadillo graphics." 

Some minor changes have been made in the names of a few ATARI 
PILOT commands because of collisions with existing valFORTH names. 
Important variations are listed here: 


PILOT 

valGraphics 

CLEAR 

WIPE (CLEAR exists) 

FILL 

PHIL (FILL exists) 

FILLTO 

PHILTO (for consistency) 

QUIT 

(not needed and exists) 

PEN ERASE 

0 PEN (ERASE exists) 

LOCATE 

LOOK (LOCATE exists) 


It should be mentioned that for this package, virtually the entire 
set of ATARI operating system graphics functions have been replaced by 
much faster (approximately 6 times) and much smarter graphic routines. 
Highlights of these improvements are: 

* The PHIL and PHILTO functions allow filling to the left and/or 
right, filling across areas already filled, filling until a 
specific color is hit, filling until a specific color is not hit 
(i.e., re-filling), filling until hitting a set boundary regardless 
of what lies in the way, filling by either replacement or exclusive 
OR'ing, and filling into or out of corners without artifacting. 

* The DRAW and DRAWTO functions allow drawing by either replacement 
or exclusive OR'ing, drawing until hitting a specified color, 
drawing until a specific color is not hit. Additionally, lines 
are more symmetric, and optional starting point plot is supported 
(the Atari routines never plot the first point of a line). 

* All line drawing and fill routines allow plotting in wide and narrow 
screen width settings as well as normal ones, allowing true full 
screen graphics and memory conservative graphics, for the advanced 
programmer. 
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* Graphic mode 7+ ("7 and a half") is fully supported and is activated 
like any other graphic mode by using the GR. command and standard 
options. This mode is the four-color high-resolution graphic mode 
found in most of the better video games available for the Atari 
computers. (Antic mode 14.) 

* Display windowing and clipping is full supported. Options include 
"machine specific" coordinates for speed and "scaled" coordinates 
for portability. 

* TURNTWD (turn toward) and 2LNX (two line intersection) commands are 
available allowing simplified perspective drawing. 


Although the Atari 400/800 computers have extensive graphic capabilities 
the need to keep the ROM operating system under 1QK apparently forced Atari 
to omit the highest resolution color graphic mode (graphic mode 7+) and allowed 
only inefficient draw and fill routines to be implemented. Since this severely 
limited the usefulness of the computer for plotting, both of these problems have 
been corrected. 


A_ New Graphic Mode 

Many of the better video games for the Atari 400/800 computers use 
a color graphic mode not supported in BASIC. By redefining the GR. 
command, it was possible to implement this previously unavailable mode. 

This new graphic mode, which in this package is called graphic mode 12, 
is similar to graphic mode seven. The difference is that a pixel ( a 
single dot) in graphic 12 is half as tall as the same pixel in graphic 
mode 7. This mode is activated in the same manner as other graphic 
modes: 


12 GR. 

All options (i.e., split/full screen etc.) available for other 
modes will work with this new mode. In the split screen graphics 
12 mode, there are 160 horizontal by 160 vertical pixel locations. 

In the full screen mode, there are 160 horizontal by 192 vertical 
locations. Note that to use this mode the valGraphics package must 
be loaded and the new draw routines must be used (the operating system 
routines fail in this mode). 


Draw and Fill Routines 


Because the line and fill routines in this package represent 
significant enhancement to the original operating system routines, 
an explanation of the why's and how's of this implementation is 
offered in the following. 



It was first decided that the line-drawing routines must be speeded 
up so as to at least be in the class of routines of other 8 bit graphic 
machines. Because of the differing bit structures in the various graphics 
modes, these routines take up about 1000 bytes of memory. This was deemed 
a reasonable tradeoff. Since a complete rewrite had thus been elected, 
the opportunity was taken to expand the versatility of the routines, 
trading a small portion of the speed increase already gained. Several 
capabilities were deemed desirable and were implemented: 

* As mentioned above, the draw routines work in graphics mode 12. 

* Assuming that display memory has been properly laid out, the draw 
routines work in wide and narrow screen widths as well as the normal 
ones. 

* The draw and fill functions, at user option, XOR rather than replace 
pixels in display memory so that new images can be written over back¬ 
ground images. (Images are then erased by rewriting, restoring the 
background image.) 

* The draw and fill functions can detect a variety of conditions so as 
to allow concepts like "draw until" and "draw until not" as well as 
"fill until" and "fill until not." 

* The fill function allows the edge color and the surface color to be 
different, at user option, with the default setting that they are 
the same. 

* The fill function allows filling to the left, right, or both 
simultaneously, at user option. 

* Fills are able to start from and pass through corners without 
artifacting, at user option. (Implemented for vertical draw only.) 

* Simple initialization of draw functions for custom display lists 
is provided. 

These features were implemented and will be described shortly. 



STROLLING THROUGH va]GRAPHICS 


Walking the Armadillo 

To get started, insert your valGraphics disk and load in the armadillo 
package and all optional graphics packages ("+'s") (including the demos). 

It would even be a good idea to SAVE a copy of this system in case you 
crash later on. (Insert a formatted disk and type SAVE.) The load 
addresses may be found on screen 170 of the disk. Note that you do not 
need, and probably won’t want, to first load the graphics package provided 
on your valFORTH 1.1 disk. Note also that as these packages load, some 
load comments may be reported as "xxxx Is not unique" and can be ignored. 
This message simply states that a word has just been defined with the 
same name as an already existing word. 

When plotting in BASIC, location (0,0) is in the upper lefthand 
corner of the video display. All horizontal and vertical positions to the 
right and down are referenced with positive offsets from the (0,0) point. 
Armadillo graphics uses a somewhat different method to specify a location. 

In armadillo graphics, the point (0,0) is located in the center of 
the display. Horizontal locations to right are referenced with positive 
offsets from this point, while locations to the left are referenced using 
negative offsets. Likewise, locations higher on the screen from the origin 
are referenced with positive vertical offsets while those lower on the 
screen are referenced using negative ones. Since this setup follows the 
standard cartesian coordinate system, function plotting is greatly simpli¬ 
fied. 


270° - X 

(-90°) 


0 U 

(360°) 
+ Y 


- Y 
180° 
(-180°) 


+ X 90° 
(-270°) 


Let’s take a look at 


the basic armadillo graphic commands. 


Type: 


8 GR. 


ON ASPECT 



This will put the system into graphic mode 8 with the armadillo positioned 
in the center of the display facing upward (0 degrees). The "dimensions" of 
the display are 320 pixels wide and 160 pixels high. The boundaries are set 
from -159 to 159 left-to-right, and 79 to -79 top-to-bottom. (The lowest 
line of pixels and the furthest right are excluded for code symmetry and 
shortness.) The command "ON ASPECT" will be explained later, but basically 
it ensures that squares will look like squares and not like rectangles (as 
in BASIC). First let's turn the armadillo to the right. To change its 
direction, we use the TURN command: 

90 TURN 

This command turns the armadillo clockwise by 90 degrees from its current 
direction. To draw a line (and move) the armadillo, the DRAW command can 
be used. Try this: 

30 DRAW 90 TURN 50 DRAW 

A short line should have been drawn toward the right — 30 steps in the 
direction the armadillo was facing. The 90 TURN command was then used 
to aim the armadillo downward, and 50 steps in that direction were taken. 

The DRAW command moves the armadillo the specified number of steps in the 
direction that it is facing. Note that a negative step count tells the 
armadillo to draw in the direction opposite that in which it faces. It 
is also possible to move the armadillo to a specified point on the screen 
regardless of which direction it is facing. The DRAWT0 command is used 
for this: 


0 -60 DRAWT0 0 TURNT0 

Although the armadillo was facing down, it moved directly to the 
point (0,-60). Note that although it moved diagonally, it still is 
facing directly downward (to 180 degrees). The TURNT0 command is used 
to face the armadillo in the specified direction regardless of where 
it is currently facing. In this case, the armadillo is turned to face 
0 degrees. 

In addition to drawing lines as it moves, the armadillo can fill 
in areas of the display. The PHIL command is used for this purpose 
and functions very much like the DRAW command. (FILL is already 
defined and if used mistakenly for PHIL, the system will probably 
crash.) Try this: 


20 PHIL 

This commands the armadillo to take 20 steps in its current direction 
filling the surface area to its right as .it goes (the area to the left 
can be filled also — more on that later). Similar to the DRAWT0 cornnand, 
there is also a PHILT0 command which works just like PHIL except that the 
armadillo moves to a specified point regardless of the direction it is 
currently facing. To PHIL to the origin (0,0), use: 

0 0 PHILT0 

The PHILT0 command should have filled straight up to the point (0,0), 



So far, we have used the TURN, TURNTO, DRAW, DRAWTO, PHIL, and PHILTO 
commands. These are the basic "drawing" words, used constantly, when work- 
ing with armadillo graphics. You will encounter times when you need to 
move the armadillo without drawing a line between its starting point and 
its destination point. There are four similar commands which allow this. 

The GO, GOTO, GO., and GOTO. All reposition the armadillo without drawing 
a line. The GO and GOTO commands function like DRAW and DRAWTO respectively; 
however, the armadillo is placed at the position where the last dot of the 
plotted line would have been and no line is drawn. GO. and GOTO, function 
like GO and GOTO; however, a single point is plotted at the destination 
point. Try this: 

~30 0 GOTO. 180 TURNTO 

10 PHIL 10 GO 10 PHIL 10 GO 10 PHIL 

0 -60 DRAWTO 

After entering the above, type FRAME to frame this picture. If all went 
well, your display should look like: 





1 
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Let us now explore the new graphic 12 mode. In this mode, there 
are four colors numbered zero to three. When the armadillo is moved, 
there must be some way to specify which color to DRAW with. The PEN 
command is used for this purpose. Enter the graphic 12 mode by typing: 

12 GR. ON ASPECT 

The GR. command automatically sets the draw color to one (usually 
red). Let's draw some colored lines now: 

10 DRAW (draw in color 1) 

2 PEN 10 DRAW (draw in color 2) 

3 PEN 10 DRAW (draw in color 3) 

You should now have a vertical red, green, and blue line. Note that 
color 0 is black (actually background) and is used primarily for erasing 
lines. Besides setting the draw color, the PEN command also sets the 
PHIL color. 


-50 0 GOTO 45 TURN 

2 PEN 10 PHIL 

After positioning the armadillo in a good position for filling, the draw 
and fill color is set to 2 (usually green) and 10 steps are taken. By 
using PHPEN comnand, it is possible to set the PHIL color to something 
other than the PEN color. PHPEN stands for "phi1-pen" and is used in 
the same manner as the PEN command: 

3 PHPEN 32 PHIL 

Note how the edge line remains the color set by the last PEN command, 
while the PHIL command uses the color set by the last PEN or PHPEN 
(whichever came last) command. The PHIL color is always set by the PEN 
command for convenience. Experiment with this a bit. 

To clean the current display, the WIPE command is used. Usually 
after wiping the display, the armadillo is repositioned to the center of 
the screen using either the CENTER or CENTERO command. The CENTER command 
simply does a "U 0 GOTO" while the CENTERO command does a "CENTER 0 
TURNTG". 


WIPE CENTERO 

Either right or left filling can be performed, as well as both 
simultaneously. The two commands RPHIL and LPHIL take an ON/OFF value 
and instruct the next PHIL or PHILTO command to take appropriate action. 
The default setting is "ON RPHIL" and "OFF LPHIL". The command DINIT will 
return all settings to their default values. This is especially valuable 
when learning, as It is easy to get fouled up . Type in the following set 
of cormiands and observe what happens: 

50 50 PHILTO 

CENTER OFF RPHIL ON LPHIL 
-50 50 PHILTO 

CENTER ON RPHIL 1 PEN 

40 PHIL 



This demonstration first shows right filling, then left filling, 
and then simultaneous right/left filling. Note that although there was 
nothing on the screen to halt the right/left fills, they still stopped 
upon hitting the edge of the display. In fact, by using windows (which 
will be described later), fill boundaries can be set anywhere on the 
screen and fills will never occur outside of those boundaries. This is 
invaluable when trying to restrict drawing and filling to a select 
portion of the display. 

Another unique feature of the fill routines is that they allow 
filling over any pseudo-background color (default is 0). The PHBAK 
command is used to specify this background color. Like the PEN and PHPEN 
commands, PHBAK accepts a color specification on the stack. WIPE uses 
the color specified by the last PHBAK command, and the fill routines 
recognize this as background to be filled over. Try this: 

3 PHBAK WIPE 

CENTERO 0 PEN 1 PHPEN 

50 50 PHILTO 

For the time being, we will leave the background color blue and 
continue on. Next we are going to define a few words which will draw 
simple shapes. Bear in mind that when defining shape words, TURNTO, 

DRAWTO, and PHILTO should be avoided as they are absolute in nature. 
Typically, figures should be drawn relative to the armadillo's direction. 
Likewise, the armadillo should generally be returned to its original 
position and heading once the "canned" shape has been drawn. (For the 
curious, the words DX1 and DY1 return the x-y coordinates of the armadillo's 
current location. The word DAZM returns the directional angle of the 
armadillo.) We shall now define a word which will draw a square on the 


screen. 



: SQUARE 


( #steps/side — 

DUPDRAW 

90 TURN 


DUPDRAW 

90 TURN 


DUPDRAW 

90 TURN 


DRAW 

90 TURN ; 



WIPE CENTERO 2 PEN 
20 SQUARE 

45 TURN 2(3 SQUARE 


There are several points to be mentioned here. First, because 
combinations of DUP with DRAW, 60, and 60, occur often, the words DUPDRAW, 
DUPGO, and DUP60. have been defined to conserve memory. 

Also notice that the squares drawn really have sides of equal length 
(in BASIC, the vertical legs would be much shorter). The armadillo package 
performs "aspect ratio" calculations which ensures that "equal" lines are 
drawn the same length regardless of their orientation to a fixed axis. 

These routines were enabled at the beginning of this stroll with the 
"ON ASPECT" command. Because these calculations do take time (approxi¬ 
mately 3 milliseconds per draw), they can be turned off using the command: 


OFF ASPECT 



Now, notice how in the last example, the second square was rotated 
45 degrees from the first square. We can write simple words using this 
effect that look pretty snappy on the screen: 

: FAN ( #steps/side — ) 

20 0 (20 squares for fan ) 

DO 

18 TURN ( 360 degrees/20 = 18 ) 

DUP SQUARE 
LOOP 
DROP ; 

WIPE CENTER 30 FAN 

This word draws 20 squares on the screen each offset from each other 
by 18 degrees. Try changing PEN colors and give different step sizes to 
FAN and watch the results. Each of the boxes drawn by FAN is the same 
size. We can write another simple word which will slightly increase the 
size of each box drawn and obtain a different effect: 

: WHIRL 

( #boxes ) 0 
DO 

I 3 / SQUARE 
5 TURN 
LOOP ; 

WIPE CENTER 250 WHIRL 

This word draws the specified number of boxes, each one rotated from 
the last by 5 degrees. After three boxes are drawn, the box size is 
increased. This is how the swirl effect is obtained. A slight variation 
of this is to change the PEN color before each square is drawn, but this 
is left to the reader. 

Up to now, we have drawn lines from one point to another regardless 
of what the line replaces. This is standard for line drawing routines. 

In the valGraphics package, however, "draw until" is supported. In other 
words, lines can be drawn that will stop on the first occurrence of another 
line (actually, until the color specified by PHBAK or DRBAK, whichever 
came last). When the draw-until switch DRUNT is ON, all DRAW, DRAWTO, PHIL, 
and PHILTO commands will stop when the base line hits another line on the 
display. Here’s an example: 

ON DRUNT WIPE CENTERO 
40 SQUARE 

Don't worry if only the two vertical sides of the square were drawn, this 
is normal. Since the draw routines in this package plot both the end 
point and the starting point, the end point of the first side stopped 
the line draw of the second side. In most cases, this is the desired 
function for DRAW, but while drawing-unti1 (ON DRUNT), first point plotting 
is not desired. For this reason, it can be easily turned off using the 
DR1ST switch: 

OFF DR1ST WIPE 
40 SQUARE 


( #boxes — ) 

( increase size ) 



With DRUNT still on, try the following example: 

WIPE 30 QCIRCLE 
40 SQUARE 

The QCIRCLE command draws a quick-and-dirty circle about the 
armadillo, with the value on top of stack taken as the approximate 
radius. Notice how the 40-step square turned out. Because the draw- 
until mode is on, each side is drawn until another line is encountered. 
Note, however, that even though the line was not drawn to the destina¬ 
tion point, the armadillo was still positioned there. Because interest¬ 
ing results can be obtained by using this feature, the RELOC command 
must be used explicitly to reposition the armadillo to the last plotted 
point of the line. The following two definitions might come in handy: 

: DRWUNTIL ( #steps — ) 

DILLO 
0M DRUNT 
DRAW DFLG 
IF RELOC ENDIF 
OFF DRUNT ; 

: DRW2UNTIL ( x y — ) 

DILLO 
ON DRUNT 
DRAWTO DFLG 
IF RELOC ENDIF 
OFF DRUNT : 

(DFLG is a flag set true only if the last DRAW or DRAWTO crossed 

the current window.) 

These two commands will automatically reposition the armadillo at 
the end of the drawn line after each draw. One last point about draw- 
until -- occasionally it is desirable to know when a draw-until line was 
stopped by the draw-until function, rather than by reaching an end point 
or window boundary. The 7DRSTP word will return a one (1) if the last 
line was stopped, otherwise it will return zero. Try drawing a few lines 
and verifying this. ?DR$TP is in the DILLO vocabulary. (See the glossary.) 

Up until now, when we filled areas or drew-until, both the fills 
and draws would stop when encountering a non-pseudo background color (set 
by PHBAK or DRBAK). Often, it is desirable to refill an area (i.e., 
fill until background is hit) or draw-until hitting the pseudo background 
color. There are two switches which can be turned ON or OFF as desired. 

The PHUNOT (fill until not) switch, when ON, fills until the color set 
by the last PHBAK command is not hit. This is the defaulat condition 
(i.e., fill until background is not hit). When OFF, the fill routines 
continue to fill until the pseudo background color is hit. Likewise, the 
DRUNOT (draw until not) switch, when ON, draws until the color set by the 
last PHBAK or DRBAK (whichever came last) command is hit. Let's take a 
look at this: 

DINIT (Reset draw/fill switches) 

2 PEN 3 PHPEN 

WIPE CENTERO 50 50 PHILTO 

1 PHPEN 180 TURNT0 

OFF PHUNOT (fill while not background) 

OFF RPHIL ON LPHIL 60 PHIL 
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As you may recall, the DINIT command initializes all eleven switch 
settings (five of which have yet to be introduced). Next a normal right 
fill (filling over background) is performed. The PHUNOT switch is then 
set for filling while not background and a left fill is performed. 

Notice that no filling occurred when the base fill-line extended out of 
the previously filled area. 

DRUNOT works in the same manner. Execute the last example a second 
time, but turn both PHUNOT and DRUNOT off where previously just PHUNOT 
was turned off. Also turn DRUNT on. This time, no line should extend 
past the previously filled area. (Note that the base line of a fill 
responds to ail the draw switches). 


To finish off this first part of the stroll, the final five draw 
switches will be explained. Briefly, they are PH-DR which allows the 
base line of a fill to be drawn or not, DRXOR and PHXOR which allow 
lines and fills to be XOR'd into place, PHCRNR which enables/disables 
rudimentary corner check tests for filling, and PHUNT which allows 
filling to the edge regardless of what lies in the way. 

The PH+DR switch is available because there are times when it is not 
desirable to actually draw the base line of a fill. This is the case when 
PAINTing (i.e., "shape filling," which is not supported but may be imple¬ 
mented). The default value for PH+DR is ON,. When PH+DR is OFF , the' 
pixels where the base line should be drawn are left untouched. 

t The DRXOR and PHXOR switches allow lines and fills to be 
XOR'd into place. This has the useful property that by simply redrawing 
or refilling the exact same line or shape the object will erase itself. 

For a good example of this, we can use graphic mode 8: 

8 GR. DINIT 250 WHIRL 

1 PHBAK ON DRXOR WIPE 

Recall that the WIPE command uses the value set by the PHBAK comnand— 
in this case, one. WIPE is defined to use a multiple DRAW and therefore 
responds to most (but not all) of the draw switches. Because the WIPE is 
performed with the DRXOR mode on, the display is inverted. WIPE the dis¬ 
play a second time to re-invert it. To erase the display, DRXOR must 
be turned off. Try this: 

0 PHBAK OFF DRXOR WIPE ON DRXOR 

1 PEN CENTERO 40 FAN 

40 FAN ( one more time ) 

It is important to remember that lines drawn with pen zero have no 
effect in the DRXOR mode. Likewise, first point plot should generally be 
turned off when DRXOR is on otherwise endpoints will be lost. Now to 
demonstrate PHXOR and PHUNT try these examples: 

DINIT WIPE (normal situation) 

CENTERO 100 WHIRL 50 50 PHILT0 



Now with PHUNT off: 


CENTERO OFF PHUNT 50 50 PHILTO 

The last fill command should have filled clear to the edge of the display, 
ignoring everything in its path. Using this with PHXOR, interesting results 
can be obtained: 

WIPE CENTERO 50 FAN 

ON PHXOR 50 50 PHILTO 

Now, try: 

CENTERO 50 50 PHILTO 

By using windows (described later), the fill and draw commands can be 
restricted to selected areas of the display. In combination with windows, 
PHXOR can produce astounding visual effects (especially in GTIA modes). 

The last remaining switch to be described is the PHCRNR switch. 

PHCRNR allows rudimentary corner checking for vertical fills. Because 
its use is specialized, PHCRNR is normally turned off. The following 
example will show its function: 

DINIT CENTERO WIPE 

50 GO 50 0 DRAWTO 0 0 DRAWTO 50 PHIL 

Notice the artifact at the top corner. Now, turn PHCRNR on and perform 
the same example (less the DINIT command). This time, no artifact should 
have appeared. It is important to remember that these corner tests will 
not work with many diagonal fills, and completely fail when refilling an 
area. Also note that when first point plot is disabled, even vertical 
filling fails. 

All of the basic armadillo commands have been explained and are 
summarized in the glossary and on the valGraphic Handy Reference Card. 
Although many commands have been discussed, there are many more left 
to talk about. These include the perspective drawing commands for 
three dimensional displays, and the complete set of window commands 
which will be described next. 


(NOTE: In all of the above examples, WIPE has been used to 
clear the display. In many cases, the memory FILL 
command can be used instead: 88 @ n 0 FILL where 
n is the size of display memory in bytes. This method 
is much faster but cannot be used with windows.) 



STROLLING THROUGH valGRAPHICS, PART II: 
Windows, Lines and Labeling 


Windows 

Up until now we've been working in the base window that is set up when using 
the GR. command. Let's compose some other windows. Type: 

12 GR. 

FRAME 
10 QUBE 

-50 -10 30 -10 WINDOW 

FRAME 

DOT 

We entered graphics 12, framed the base window, made a window whose left, right, 
top, and bottom edges were at -50, -10, 30, and -10 respectively, framed it, and 
then put a dot at the armadillo and found that it was at the center of the new 
window. Now type 

25 QUBE 

and note that the cube is clipped within the boundaries of the new window, not 
the old one. This could be very useful, say, in showing what was visible through 
a "real 11 window in a house that you had drawn, without going to a lot of extra 
trouble to restrict the image to the house's window. Now type 

WIPE 
CENTERO 
25 QUBE 

Nothing happens. This is because CENTERO centered the armadillo in the base 
window. We need to use a different word to re-center in the new window. Type 

WCTRQ 25 QUBE 

That's more like it. WCTRO stands for "Window CenTeR 0 turnto," and there is 
also just a WCTR, for "Window CenTeR." Let's try some of the other tricks 
from before: 

3 PHBAK 

WIPE 

WCTR 

20 QUBE 

FRAME 

ON DRXOR 

WIPE 

Get the idea? When we did ON DRXOR, the draw routines, which are used by WIPE, 
started doing an XOR instead of a replace, with the same effect as we've seen 
before, but this time restricted to a smaller window. Type 



DINIT 

WIPE 

DOT 


to get things back to normal. Note that DINIT returns to the base window and 
so WIPE wipes the entire screen. The window in which we were just working is 
forgotten. (We'll discuss ways to remember it a little later.) DOT shows that 
the armadillo is back at the center. Now type 

ON ASPECT 

-50 -10 30 -10 WINDOW 

FRAME 

and you see that this "same" 40 by 40 window as before now looks much more 
nearly square. This illustrates that ASPECT works on windows as well as lines. 
With ASPECT on, what you give up in order to get better shapes is some informa¬ 
tion about what coordinates the top and bottom of the screen actually are, but 
for "hands on" use this is not much of a loss. Let's make two more of this 
type of window: 

2 PEN 

0 30 20 -30 WINDOW FRAME 

DOT 


OK, and then 

-30 30 90 -90 WINDOW 

Notice that this window is larger than the base window. Now type 

DOT 

FRAME 

and notice the trash in the text window. If you choose to make a window 
larger than the base window, the system will not protect you; it assumes that 
you know what you're doing. 

Type CIS once or twice to clear the screen. Then type 
12 GR. 

10 50*-10 -60 RELWND 
FRAME 

2 PEN 
40 QUBE 

Interesting. Now a 40 QUBE used to be much bigger; but because we typed RELWND 
instead of WINDOW, objects are drawn relative to the new window, as if it were 
the base window. Type 

3 PHBAK 
WIPE 
FRAME 

10 50 -10 -60 RELWND 

FRAME 

40 QUBE 


XL 1 — 15 



Get the idea? Relative windows are useful for all sorts of tricks. Often, it 
would be helpful to be able to return to a window, and relative windows are the 
hardest to reconstruct. Try typing, on one line, 

THISWND LIVING-ROOM 

(Defining words should always be followed by the name of the new word on the 
same line.) 

By typing LIVING-ROOM later on we can return to this window, as a relative window, 
with no further work. To demonstrate, type 

0 PHBAK 
WIPE 
BASWND 
ON DRXOR 
1 PHBAK 
WIPE 

-20 0 20 0 WINDOW WIPE 

THISWND MY-ROOM 

LIVING-ROOM 

WIPE 

50 QUBE 

MY-ROOM 

50 QUBE 

Normal windows, created by WINDOW, of course can also be named more directly: 

: window-name number number number number WINDOW ; 
and you've got it. 

Well, what else? Type 
40 GR. 

What have we here? 40 is 32 + 8 so we've entered 8 GR. without pre-erasing. 

(This is one of the standard GR. options, you'll recall.) Since 12 GR. and 
8 GR. occupy exactly the same display memory, what we see is the 12 GR. image 
data interpreted as 8 GR, Four color 8 GR. This effect has been written up 
in various places, and here it is. You can come back and play with this sometime. 
Right now, type 

DINIT 

WIPE 

DOT (you may not be able to see it on your screen 
without adjustment.) 

0-30 GOTO 60 DRAW 

30 0 GOTO 270 TURNTO 60 DRAW 

(Now it's more visible) 

87-31 GOT 0» 

(Move away) 

0 0 TURNTWD ("turn-toward") 

100 DRAW 
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You ! ll notice that the line doesn't hit 0,0 exactly. This is because the 
armadilio's direction is only represented to the nearest degree. Still, this 
is good enough for most purposes. 

Finally, let's draw the a rectangular solid in two-point perspective. 

(The procedure in this example is not necessarily the best one, but it 
illustrates several capabilities. You might want to have the debugging 
package loaded from the valFORTH 1.1 disk, and have the stack turned on. 

That way you can follow the action on the stack also.) First we set up a 
horizon and two vanishing points: 

WIPE 

-200 60 GOTO 90 TURNTO 500 DRAW 

-100 60 NAMEPT VP1 (name the point on stack) 

100 60 NAMEPT VP2 

Then we "construct" the solid 

CENTER VP1 TURNTWD 40 DRAW 

THISPT PT1 (name the present point) 

CENTER VP2 TURNTWD 30 DRAW 
THISPT PT2 
CENTERO 20 DRAW 
THISPT PT3 

VP1 TURNTWD MAKLN (leave a "line" on the stack) 

PT1 GOTO 0 TURNTO MAKLN (leave a second line) 

2LNX (find their intersection) 

NAMEPT PT4 (and name the point) 

PT4 DRAWTO PT3 DRAWTO 

VP2 TURNTWD MAKLN (do it again) 

PT2 GOTO 0 TURNTO MAKLN (second line) 

2LNX (intersection) 

2DUP GOTO (make a copy then go there) 

PT3 DRAWTO PT2 GOTO 2DUP DRAWTO (put in 2 more lines) 

VP1 TURNTWD MAKLN PT4 GOTO VP2 TURNTWD MAKLN 2LNX 
DRAWTO DRAWTO (finished) 

0 GR. VLIST (see the new words: point names.) 

40 GR. (Still there.) 

In addition to MAKLN there is also THISLN which name the line the armadillo 
lies on, and NAMELN which will name a line on the stack. Given two points on 
the stack, 2PT-LN will change the four values into three, suitable for use 
with NAMELN. Practice, and some study of the glossary, will help. The user 
should realize that points and lines can't be named very easily within a 
program, but only while the program is loading. Within a program, use the 
stack or array structures for saving points and lines. 

This stroll is not meant to exhaust the possibilities of this package, but 
merely to indicate them. A clever programmer, for instance, would have little 
trouble in figuring out how to interface this package to a joystick to make a 
very versatile sketchpad. 

Hmmmmm? 
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valGRAPHICS GLOSSARIES 


Turtle graphics, and so also valGRAPHICS, uses a coordinate system different 
from that used by the Atari OS. In valGRAPHICS, the center of the graphics 
display is the point o,o. "x" values are positive to the right and negative to 
the left, while "y" values are positive toward the top of the display and 
negative toward the bottom. The maximum values of x and y may vary between 
display modes, depending on various user options that are selected. In this 
regard, see examples in the "Strolling Through valGRAPHICS" sections of this 
package, and also the words MCGOR and SCOOR in the "Windows" section below. 

In the glossary that follows, all mention of coordinates willnapply to valGRAPHICS 
coordinates rather than to Atari OS coordinates. 

The DRAW, DRAWTO, PHIL, and PHILTO commands support a number of options 
with a fair degree of complexity and power when used fully. These commands and 
options are discussed as a group at the end of the glossary and summarized with 
a' chart which also appears on the handy reference card. The functions discussed 
are necessarily complex; however, the command DINIT ("d-init") is provided so 
that the user may return the system to a "standard-option" status during 
experimentation and practice, or during actual program execution. 

The term "pixel" stands for "picture element" and refers to the smallest 
"point," which may be drawn in a given graphics mode. 

As usual, "color" specification numbers refer to color registers. The 
actual colors in the color registers may be changed by various means, including 
loading the COLOR COMMANDS package from the valFORTH 1.1 disk and using the 
SETCOLOR or SE. command. 

On GTIA-equipped machines in 10 GR. there are nine colors available, 
because the four player/missile color registers are also used. Since these 
registers sit just below the pi ay field, color registers in memory, they may be 
set by using negative "piayfield" numbers when using SE. . For instance, -3 
PINK 6 SE. will set player/missile 1 (= -3 + 4) to PINK 6. 

0 n GTIA-equipped machines in 9 GR. the "color" set by the various color 
commands below, e.g. PEN, PHPEN, PHBAK, etc., is interpreted explicitly as 
luminance between 0 and 15. The hue is that of the background color register. 

On GTIA-equipped machines in 11 GR. the "color" set by the various color 
commands below is interpreted explicitly as a hue between 0 and 15. The Turn 
is that of the background color register. 

The term "armadillo" rather than "turtle" will be used in this package. 

DILLO (short for armadillo) is a vocabulary that branches from FORTH. 

All of the system words in this package have been put in the DILLO vocabulary 
to keep them out of the way during VLIST and other tasks. Some little-used 
words are also in DILLO, though advanced users may want to get at them. To 
enter the DILLO vocabulary simply type DILLO and these words will now be 
recognized by the system. Note that since the word : generally puts the 
system back into the FORTH vocabulary, DILLO may have to be used within a 
colon definition., See the source code for numerous examples of this. Words 
in the DILLO vocabulary are so specified in the glossary below. (The word 
DILLO is immediate.) 

For clarity, some definitions may be repeated. Within this glossary, 
however, the same name indicates the same word. 



valGRAPHICS Glossary 
Part I of III 

General Functions: ^ 

GR. ( n — ) 

Appears to function as always, but is now much more powerful: 

* For n = 12, or 12 with higher bits set for the usual options, the mode 
known popularly as 7+ will be activated. This mode is set by Antic instruction 
14 and its characteristics are listed on the handy reference card which 
accompanies this package. 

* For n = 3 to 12, (possibly with higher bit options), the appropriate graphics 
mode will be set up, and all armadillo parameters will be initialized. Note, 

of course, that if your machine does not have a GTIA chip, then modes 3, 10, 
and 11 will not operate as they should. 

* For n = 0 to 2, (plus higher bit options), the system will respond as usual. 

* GR. initializes a number of system and user quantities. Data about pixel 
and display-memory dimensions are sent to appropriate addresses. A pen color 
register of 1 is set by 1 PEN, and the-background color register for fill 
commands is set to 0 by 0 PHBAK. OFF ASPECT is executed. 

PEN ( n — ) 

This command is used to change the color that the armadillo draws with. ^ 

PEN sets a new color register, n, to be used by the DRAW, DRAWTO, PHIL, and 
PHILTO commands. 

PHPEN ( n — ) 

This command is used to change the color that the armadillo fills with. 

PHPEN sets a new color register, n, to be used by the PHIL arid PHILTO commands. 

Note that PEN also sets a new color register for PHIL and PHILTO, so the value 
used by PHIL and PHILTO will be determined by whichever command, PEN OR PHPEN, 
was done last. 

DRCLR ( — b ) 

Returns the present color used by the armadillo for drawing. DRCLR is 
in the DILLO vocabulary. 

PHCLR ( — b ) 

Returns the present color used for filling. PHCLR is in the DILLO 

vocabulary. 

GO ( n — ) 

GO moves the armadillo n units in the direction in which it is facing. 

No lines are drawn or points plotted. ^ 

DUPGO ( n - n ) 

Same as GO, but doesn't destroy stack argument. 
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GO, 


GO, moves the armadillo n units in the direction in which it is facing 
^ and then pokes the pixel at its new location with the value set by the last 

PEN command, 

DUPGO. ( n — n ) 

Same as GO., but doesn't destroy stack argument, 

DOT ( — ) 

DOT puts a dot of the present armadillo color, set by PEN, at the present 
armadillo position. 

GOTO ( x y — ) 

GOTO positions the armadillo at x,y. No lines are drawn or points plotted. 
GOTO, ( x y — } 

GOTO, positions the armadillo at x,y and pokes the pixel at the new 
position according to the color register selected by the last PEN command. 

CENTER ( — } 

Positions the armadillo at the point 0,0. The direction the armadillo 
is facing is unchanged. 

^ CENTERG ( — ) 

Positions the armadillo at the point 0,0 and turns it to face 0, i.e., 
straight up, 

REL.0C { — ) 

Positions the armadillo at the last point drawn by the system routines. 

This is a special purpose command and is used in conjunction with clipping 
in windows, and with the "draw-until" option, described elsewhere. RELOC is 
in the DILLO vocabulary, 

ASPECT ( ON or OFF - ) 

ON ASPECT will cause vertical components of subsequent graphics commands 
to be scaled to account for the fact that pixels are not square. Thus, circles 
will be rounder, squares will be squarer, and so on. Of course, shapes that 
previously fit on the screen may not fit any longer, as a result of the 
vertical expansion. OFF ASPECT will turn the compensation off for subsequent 
commands. OFF is the default mode, but this may be altered by changing "OFF 
ASPECT" to "ON ASPECT" at the end of the source code for GR. 

LOOK ( x y — b ) 

This command returns the value of the pixel at location x,y. LOOK does 
^ not move the armadillo. For exampTe, to find the color of the pixel under 

the armadillo, use the armadillo's coordinates: DX1 DY1 LOOK. 
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DX1 


( - n ) 


Returns the x coordinate of the armadillo. 

DY1 ( - n } 

Returns the y coordinate of the armadillo. 

TURN ( n - ) 

Changes.the direction that the armadillo is facing by n degrees clockwise. 

Hence, if n is negative, the armadillo will turn counter-clockwise. 

TURNTO ( n — ) 

Turns the armadillo to a heading of n degrees from vertical. Hence, 

0 TURNTO points the armadillo toward the top of the display, and 90 TURNTO 
points the armadillo toward the right edge of the display, and -90 TURNTO or 270 
TURNTO both point the armadillo toward the left edge of the display. 

TURNTWD ( x y — ) 

Turns the armadillo so that it faces toward the point x,y. "Turn-toward." 

DAZM ( - n ) 

Returns the direction, in degrees (0-359), in which the armadillo is 
facing; Stands for "dillo azimuth." 

DINIT ( — ) 

DINIT stands for "armaDillo INITialize." Use it to return all options 
to their default values and to center the armadillo in the display. Useful 
during practice and experimentation. 

DRAW ( n — } 

Move the armadillo n units in the direction in which it is heading. Draw 
that portion of the line of travel of the armadillo, including the first point, 
that falls within the current window, using the current PEN value. 

DRAWTO ( x y — ) 

Move the armadillo to x y and draw that portion of the line of travel that 
falls within the current window, using the current PEN color register. 

PHIL ( n - ) 

Move the armadillo n spaces in the direction it is heading, and as in DRAW, 
color that portion of the path of travel with the PEN value. Also perform a 
fill to the right during the time that the armadillo is in the current window. 

PHILTO ( x y — ) 

' N 

Move the armadillo to the point x y. Then proceed as in PHIL,, 
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Windows and Coordinate Systems 


The following discussion is largely technical. Even so, it may be skimmed 
by the casual user, who can also get a "hands-on" feel for the operation of 
windows and coordinate systems by following the examples in the "Strolling 
Through valGRAPHICS" section of this package. The proliferation of quantities 
in this package is necessitated by allowing it to handle both "absolute" and 
"relative" windows at the same time. Because of the complex changes of coordi¬ 
nate system that this entails, a variety of different data are kept on system 
configuration. This process is transparent to the casual user but may be 
used with great power by the experienced programmer. 

This package uses cartesian (rectangular) coordinate Systems (CS's) 
throughout. For highest speed in graphics work, the graphics coordinate system 
should be in the same "scale" as the hardware. That is, moving one unit 
horizontally or vertically in the graphics CS should move the graphics cursor 
(in this case called the armadillo), one pixel. Doing this avoids additional, 
usually relatively slow, multiplication and division operations to make the 
graphics CS "fit" the hardware CS. However, sometimes the speed sacrifice is 
worthwhile in achieving a desired effect. Therefore, both types of CS are 
supported in this package. The default CS is of the first type, and it may also 
be called into play explicitly by the command "MCQOR" which stands for "machine 
coordinates." This mode is used for high-speed at some sacrifice of flexibility, 
ihe optional mode is called by "SCOOR" which stands for "scaled coordinates." 
Before executing SCOOR, the user may want to set up coordinate boundaries by 
using SET-SCALE, defined below. Moving between these two types of CS may also 
be handled.automatically by the window routines discussed next. Because of 
automatic initialization routines in GR., the user may employ both machine and 
scaled CS * s without ever calling them up explicitly. This happens through the 
commands WINDOW, which puts the system into the machine CS before interpreting 
its 4 stack arguments; and RELWND, which puts the system into scaled coordinates 
before interpreting its 4 stack arguments. (Clearly, RELWND must force the 
system into scaled coordinates, since it will be creating a window with the 
same numerical coordinates as the one RELWND works from, though the windows 
will generally be different sizes.) For some help in familiarization with these 
procedures, please refer to the examples in the "Strolling..." section. 

A "window," for the purposes of this package, is a rectanaular portion of 
the graphics display area. Windows are implemented to allow "clippinq" as 
well as some additional scaling and distortion features. Clipping allows the 
armadillo to travel inside and outside the currently active window, while allow¬ 
ing drawing and filling only while the armadillo is within the boundaries of the 
window. 

The current window's "physical" boundaries are kept in the system quans 
WNDLFT, WNDRGT, WNDTOP, and WNDBOT. (For an explanation of the QUAN structure, 
see the section on this topic.) The user does not generally access these 
quantities directly, but sometimes may want to do so for special effects. 

WNDLFT and WNDRGT are, respectively, the number of pixels from the left edge of 
the display to the left edge of the window, and the number of pixels from the 
left edge of the display to the right edge of the window. Similarly, WNDTOP 
and WNDBOT are referenced from the top of the display. Again, the user doesn't 
have to use these quantities; they are, however, the "bedrock" of the windowing 
process. These quans are in the DILLO vocabulary. 



When a graphics-type GR, command is executed (3-12, see GR, above) a window, 
called the "base window," is set up which takes up the entire graphics display 
area. (The "physical" edges of the base window are stored in the system quans 
WNDL, WNDR, WNDT, and WNDB, which have meanings similar to WNDLFT, etc., above, 
and are likewise in the DILLO vocabulary.) The user may generally return to 
the base windowat any time before leaving the graphics mode by executing BASWND. 
When the base window is made current by the user explicitly or by GR., the 
armadillo is placed at the point 0,0, i.e., the center of the window, and 
turned to 0 degrees, or straight up. The default "numerical" values of the 
window-boundaries are set so that they correspond to pixel counts vertically and 
horizontally. For instance, in 7 GR. the numerical boundaries would be +-79 
horizontally (since there are 160 pixels across the display in that mode), and 
+-39 vertically (since the mode is 80 pixels high.) These values are stored in 
the system quans WNDW, WNDE, WNDN, and WNDS, which stand for "window-west," etc. 
These values may be altered by means described below (SET-SCALE), although the 
change will slow down the draw routines because of the extra transformation 
required when not working in the "natural" coordinates of the system. 

After initializing to a graphics mode with GR., the user may use the various 
commands in this package to create graphics displays in the base window. However, 
additional flexibility is available to the user by defining new windows, as 
follows. 

The command WINDOW is used to define temporarily a rectangular area of the 
display as the current window. This definition will last until the next window 
defining command e.g., WINDOW, BASWND, GR., DINIT, etc. WINDOW defines the 
window in the coordinate system of the base window. Indeed, WINDOW does 
BASWND before proceeding. (The base window is set up automatically by GR., or 
by DEFBAS when using a customized display list.) WINDOW expects four arguments 
on the stack, namely the left, right, top and botton edges of the new window, 
expressed in the coordinate system of the base window. (RELWND ("re!-wind"), 
defines a window relative to the current window, not the base window; its 
description otherwise parallels that of WINDOW.) When WINDOW is executed, a new 
window is made current, and all applicable internal quans are altered as 
appropriate. The armadillo is centered in the new window and turned to 0 degrees. 
The numerical boundaries of the new window will be, as stated before, WNDW, WNDE, 
WNDN, and WNDS. 

(Advanced users: NOTE that, when.in a GR. mode, decimal 88 @ will leave the 
address of the byte in the upper-left-hand corner of the display. Internal 
calculations are based on this location. In general, if the user wishes to 
redirect the graphics routines in this package to a display memory area in a 
non-GR. display mode, he or she need do two things: Store the appropriate value 
into memory location decimal 88, and then execute DEFBAS, described below, to 
establish a base window. Note, however, that if vour display memory makes a 
discontinuous jump, as can occur for instance when crossing, a 4K boundary, the 
graphics routines will not function properly.) 

Additionally, the window-naming word, THISWND, is provided for ease 
simplicity in returning to a specific window. 

Reference on clipping algorithms: 

A Practical Introduction to Computer Programs, Ian 0. Angel 1. 
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WINDOW ( left right top bottom -- ) 

Sets a new window whose boundaries, expressed in the coordinate system of 
the base window (not the current window), are taken from the stack in the order 
indicated. The armadillo is centered in the new window and turned to a zero 
angle. Machine coordinates are activated. (See MCOOR). 

RELWND ( left right top bottom -- ) 

Hakes current a window whose edges are as indicated on stack in the 
coordinate system of the current window (not the base window). Scaled coordi¬ 
nates are activated. (See SCOOR). 

WIPE ( — ) 

Colors the entire current window according to the color register selected 
by the last PHBAK command. Note that since WIPE uses the system routine DRAWLN 
it will be affected by DRXOR. Hence if ON DRXOR has been executed last then WIPE 
will XOR all pixels in the entire current window with the value set by PHBAK, 
rather than replacing them with that value. This is useful for interesting and 
often eerie effects. 

FRAME ( -- ) 

Draws a line around the current window according to the color register 

selected by the last PEN command. 

BASWND ( — ) 

Makes the base window (usually the full window first put up by a GR. corrmand) 

current, centers the armadillo and turns it to 0 degrees. 

THISWND xxx, { ™~ ) 

XXXI 1 — j 

Creates,a word, xxx, which when executed makes current the window which 
was current at the time xxx was defined. Also centers the armadillo and turns 
it to 0 degrees, and restores XFORM to its state at the time xxx was defined. 
Located in the "Window Naming" package. 

DEFBAS ( left right top bottom -- ) 

Advanced users. Used to set up a base window when not using GR.. The 
values indicated are the number of pixels from the left edge of the display 
(for left and right) and from the top edge of the display '{for top and bottom). 
Before using this command, the value at decimal 88 should be set to point to the 
byte that represents the upper-left-hand corner of the display area to be used 
for graphics, DEFBAS is in the DILLO vocabulary. 



SET-SCALE 


( horiz vert -- ) 

Used'to redefine the horizontal and vertical numerical boundaries of 
windows. After executing SET-SCALE, the SCOOR (stands for "scaled coordinates' 1 ) 
command will set windows to range horizontally between +-horiz and vertically 
between +-vert. Note that the point 0,0 will remain the center point of 
windows. Since the command RELWND does SCOOR, relative windows will reflect 
use of SET-SCALE. SET-SCALE is in the DILLO vocabulary. 

MCOOR ( — ) 

Sets the horizontal and vertical numerical boundaries of windows to 
correspond to the number of pixels in each directi on in the base window. "MCOOR 1 
stands for "machine coordinates." It is not generally accessed directly by the 
user, with one exception: After having done a RELWND and returning to the base 
window by BASWND, an increase in speed may be had by executing MCOOR, if the 
user was using the default scale set automatically by GR. This is a fine 
point, but worth noting. MCOOR is in the DILLO vocabulary. 

SCOOR ( — ) 

Sets the horizontal and vertical numerical boundaries of windows to 
correspond to the default values set by GR. or by values set by SET-SCALE. 
"SCOOR" stands for "scaled coordinates." It is not generally accessed directly 
by the user. SCOOR is in the DILLO vocabulary. 


:WCTR ( — ) 

Centers the armadillo in the current window. 

:WCTR0 ( — ) 

Centers the armadillo in the current window and turns it to 0 degrees. 


Line-naming and line manipulation; point-naming 

These packages support labeling various graphics "entities" for convenience in 
recalling them subsequently, for a variety of purposes. 

Lines are stored internally as three-number quantities which are the 
(non-unique) A, B, and C parameters in standard algebraic line notation. 

(See the section on The Straight Line in Mathematical Handbook for Scientists 
a nd Engineer s, 2nd Edition, by Korn and Korn. Point/slope representation is 
Insufficient; point/azimuth representation would work but was not used because 
of some doubts concerning execution speed.) Labeling of lines is done princi¬ 
pally for subsequent geometric-construction-type operations, like finding the 
intersection of two lines, or the point where the armadillo would intersect 
a given line. 

NAMEPT xxx, ( x y — ) 
xxx; ( — x y ) 

Creates a word xxx. When xxx is executed, it returns x and y to the stack. 

T H ISP T xxx, (——) 

xxx: ( -- x y ) 

Creates a word xxx. When xxx is executed, it returns to the stack the x 
and y coordinates of the armadillo in the coordinate system of the window current 
at the time xxx was created. 

2PT-LN ( xi yl x2 y2 — a b c ) 

Takes the coordinates of two points on the stack and leaves A, B, and C 
coefficients of the line connecting two points. "Two-point-line." 

MAKLN ( — a b c ) 


Pushes to stack the A, B, C representation of the imaginary line on which 
the armadillo is sitting and along which it faces. Useful in finding where the 
armadillo would intersect a line along its current path. ("Make-line.") 

NAMELN xxx, ( a b c — ) 
xxx: ( — a b c ) 


Creates the word xxx. When xxx is executed, it returns the values a b c 
to the stack. 

THISLN xxx, ( — ) 

xxx: ( -- a b c ) 

Creates the word xxx. When xxx is executed, it returns the A B and C 
values of the line that the armadillo was sitting on and facing along when xxx 
was created. ("This-line.") 

2LNX ( al bl cl a2 b2 c2 — x y ) 

Given two lines on the stack in a b c form, 2LNX returns the point of 
intersection of the two lines. If the lines are parallel or if their point of 
intersection is very distant and would cause coordinate overflow, 2LNX will 
leave -1, -1. ("Two-line-intersection" or "Two-line-X.") 
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Options 

The basic commands, followed by the commands that operate the "switches" on 
options, are described below. 


DRAW In—) 

Standard option: Move the armadillo n units in the direction in 
which it is heading. Draw that portion of the line of travel of the 
armadillo, including the first point, that falls within the current 
window, using the current PEN value. 

ON DRXOR: XOR pixels with the PEN color instead of overwriting 
them with the PEN color. 

ON DRUNT: Stop on hitting a pixel of the value selected with the 
last DRBAK or PHBAK command, whichever was last. 

OFF DRUNOT: DRUNOT makes a difference only when ON DRUNT has been 
executed. When DRUNOT is off and DRUNT is on, lines halt upon hitting 
a pixel of the last color set by DRBAK or PHBAK, whichever was executed 
last. When DRUNOT is on, which is the default case, and DRUNT is on 
also, lines will halt upon hitting a pixel not of the last color set by 
DRBAK or PHBAK, whichever was executed last. 

OFF DR1ST: Don't draw the first point in a line. Useful when 
drawing connected lines after ON DRUNT so that the last point of a line 
won't be interpreted as the stop condition of the next line. See 
"Strolling..." for an example. 

DRAWTO ( x y — } 

Standard option: Move the armadillo to x y and draw that portion 
of the line of travel that falls within the current window, using the 
current PEN color register. 

ON DRXOR: XOR pixels with the PEN color instead of overwriting them 
with the PEN value. 

ON DRUNT: Stop on encountering a pixel of the color selected with 
the last DRBAK or PHBAK command, whichever was last. 

OFF DRUNOT: DRUNOT makes a difference only when ON DRUNT has been 
executed. When DRUNOT is off and DRUNT is on, lines halt upon hitting 
a pixel of the last color set by DRBAK or PHBAK, whichever was executed 
last. When DRUNOT is on, which is the default case, and DRUNT is on 
also, lines will halt upon hitting a pixel not of the last color set 
by DRBAK or PHBAK, whichever was executed last. 



DRAWTG (cont'd) 


OFF DR1ST: Don't draw the first point in a line. Useful when 
drawing connected lines after ON DRUNT so that the last point of a 
line won't be interpreted as the stop condition of the next line. See 
"Strolling...” for an example. 

7DRSTP ( — f ) 

7DRSTP is a quan whose value is adjusted after each DRAW and DRAWTO. 

If 7DRSTP is true (non-zero) then the last DRAW or DRAWTO was terminated 
because ON DRUM! had been executed and the line-drawing routine encountered 
a pixel whose value was that selected by the last DRBAK or PHBAK command, 
whichever was last. 7DRSTP is useful in conjunction with RELOC. 


RELOC ( — ) 

Relocates the armadillo to the location of the last pixel drawn by 
the last DRAW or DRAWTO command. If no points were drawn by the last 
DRAW or DRAWTO command, (e.g., if the line fell entirely outside the 
current window) then the armadillo is not moved. RELOC is useful in 
conjunction with ON DRUNT. See example in "Strolling..." RELOC is in 
the DILLO vocabulary. 

DRAWLN ( column row -- ) 

A system routine, not intended for general use. This high-speed rou- 
. tine replaces the DRAWTO routine in valFORTH 1.1, which used the same OS 

routine as the BASIC DRAWTO command. DRAWLN is in the DILLO vocabulary. 

PHIL ( n — ) 

Standard option: Move the armadillo n spaces in the direction it 
is heading, and ... 

As in DRAW, color that portion of the path of travel with the PEN 
value. Also perform a fill to the right during the time that the arma¬ 
dillo is in the current window. The color of the fill is set either by 
the PEN value or the PHPEN value, whichever was declared last. The fill 
will always terminate on reaching the edge of the current window if it 
has not been terminated prior to this event. The fill will also termi¬ 
nate on reaching a pixel that is not background color. In the standard 
option, the command ON PHUNT ( "phi 1 until") has been executed so that 
the fill will stop on the pixel of color register set by PHBAK, and 
0 PHBAK has been executed so that the actual background register, 0, 
will also be used as the phi 1 "background" register. ON RPHIL and OFF 
LPHiL have been executed so that the fill will be toward the right only. 

ON PH+DR has also been executed so that the line of travel of the arma¬ 
dillo is drawn in addition to the fill operation. 
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PHIL (cont'd) 

Example Options: 

1 PHBAK: The fill will now stop on reaching a pixel of color 
register 1 (in this example}/, or the edge of the window. 

ON PHUNOT 2 PHBAK: The state of PHUNOT only matters if ON PHUNT 
has been executed. The effect of PHUNOT ("fill until not") is that the 
fill will now stop on reaching a pixel NOT of color register 2 (in this 
example), or on reaching the edge of the window. 

OFF PHUNT: Turning off fill-unti1 means that now the fill will ONLY 
stop on reaching the edge of the window. 

OFF PH+DR: Turning off PH+DR means that now the routines will not 
draw the line the armadillo is moving along, and will just fill as 
indicated. 

ON LPHIL: Now the routines will also fill to the left. 

OFF RPHIL: Now the routines will not fill to the right. 

ON PHXOR: Now the routines will XOR the pixels with the PEN or 
PHPEN value, whichever was last declared, rather than replacing them 
with it. 

PHILTO ( x y — ) 

Move the armadillo to the point x y. Then proceed as in PHIL. 
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Options: 

(All words below take a flag stack argument, and leave none.) 


Switch Default 


RPHIL 

on 

LPHIL 

off 

DRXOR 

off 

PHXOR 

off 

DRUNT 

off 

PHUNT 

off 

DRUNOT 

on 

PHUNOT 

on 

PH+DR 

on 

DR1ST 

on 

PHCRNR 

off 


ON 

Enables right fill 
with PHIL, PHILTO 
Enables left fill 
with PHIL, PHILTO. 
DRAW, DRAWTO will 
xor pixels with 
line color. 

PHIL, PHILTO will 
xor pixels with 
fill color. 

Enable draw-until 
functions. 

Fill to edge of 
window or to dest. 
pixel. 

With DRUNT on, 

DRAW, DRAWTO draw 
until hit color set 
by DRBAK, PHBAK. 

With PHUNT on, 

PHIL, PHILTO fill 
until hitting color 
set by PHBAK. 

PHIL, PHILTO draw 
line as filling. 
First point of 
1ines is drawn. 

PHIL, PHILTO perform 
corner checking, 
armadillo must be 
moving vertically. 


OFF 


Disables right fill 
with PHIL, PHILTO. 
Disables left fill 
with PHIL, PHILTO. 
DRAW, DRAWTO will 
replace pxls with 
line color. 

PHIL, PHILTO will 
replace pxls with 
fill color. 

Disable draw-until 
functions. 

Fill until encounter 
ing halt pixel cond 
set by PHBAK, PHUNOT 
With DRUNT on, 

DRAW, DRAWTO draw 
until hit not color 
set by DRBAK, PHBAK. 
With PHUNT on, 

PHIL, PHILTO fill 
until hitting not 
color set by PHBAK. 
PHIL, PHILTO don't 
draw line as filling 
First point of lines 
is not drawn. 

No corner checking. 


DINIT sets all switches to their default values. 



Screen Dump 


This graphics 8 screen-to-Epson/Graftrax dump routine was contributed by William 
Volk, who also collaborated on other parts of this package. 

To dump graphics 8 screens (split or full), load this code and execute with , 
GRDUMP. Some samples are shown below. 


Scr # 

0 ( Dill os GRDUMP > 

1 

2 s DMPCOL DILLQ ( col — > 

3 -1 WNDB DO 

4 DUP 88 3 + 

5 I BYT/LN * + C5> 

6 EMIT 

7 -1 +LOOP 

S DROP 5 

9 

10 : QRPLT DILLQ ( — ) 

11 

12 27 EMIT 75 EMIT WNDB 

13 WNDT - 1+ EMIT 0 EMIT ; 

14 

15 ==> 


Scr # 

0 ( Dill os BOX-KITE 
1 

2 ; BOX-KITE 

3 8 GR. 

4 50 0 

5 DO 

6 I TCIROLE 

7 LOOP 

8 -60 60 GOTO 5 CUBE 

9 ON DRXOR 1 F'HBAK WIPE 

10 DINIT ; 

11 
12 

13 

14 

15 


Scr # 

0 ( Dillo; GRDUMP ) 

1 

2 : GRDUMP DILLO 

3 < turn off screen, on printer) 

4 PFLAG © 2 F'FLAG ! ’ 

5 < set line/inch = 9 on Epson ) 

6 27 EMIT 65 EMIT 8 EMIT 

7 < dump the screen > 

8 CR BYT/LN 0 

9 DO 

10 GRPLT I DMPCOL CR 

11 LOOP 

12 27 EMIT 65 EMIT 12 EM IT- 

13 CR CR PFLAG ! ; 

14 

15 
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Interfacing to Custom Display Lists 

^ The advanced user wishing to interface valGraphics to a custom (non-GR.) 

display list should recognize that any area of display memory in which valGraphics 
will be required to draw must be continuous. Thus, for example, if a 4K memory 
boundary is crossed, necessitating a jump instruction in the display list, the 
user must ensure that display memory itself crosses the 4K boundary smoothly. 

The location 88 decimal was used by the Atari OS to point to the byte in 
display memory corresponding to the upper left corner of the display, and has 
been adopted for the same purpose in this package. The first thing to do, then, 
is point 88 to the address in display memory that valGraphics should treat as 
the upper left corner of its drawing area. 

The second step is to set up a base window, much as the GR. provided in 
this package does. Use the word DEFBAS to do this, as described in the glossary. 
Note that this word expects its arguments as numbers of pixels, and that "left" 
and "top" will usually be 0. 

Finally, you need to tell the system what graphics mode you're drawing in. 

The word UGR. (for "user GR.") is provided for this purpose. Give it a number 
from 3 through 12, and it will set up quans like PX/BYT and so on. UGR. recog¬ 
nizes if you have set up for wide or narrow screen widths, also, and acts accord¬ 
ingly. 


Do BASWND and the armadillo is centered, pointed up, and ready. 
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A note on QUAN structures 


The "quan" is a new FORTH data structure, developed at Valpar, and being intro¬ 
duced in this package. Quans were devised to cut down on wasted memory and 
runtime encountered when using the "variable" data structure. Quans work as 
follows: (Advanced users may want to follow along in the source code for these 
structures also.) 

Defining a quan: 

QUAN BINGO 

Note that quans do not take initial values. This form was chosen to allow for 
simpler upgrading to target-compiled code later on. 

Giving a quan a value: 

1234 TO BINGO 

Note that since TO is immediate, "TO BINGO" compiles to only 2 bytes instead 
of the 4 bytes that would be required if BINGO were a variable (i.e., BINGO 1 }. 

Getting a value back from a quan: 

BINGO 

Simply saying the name of the quan will leave its value on the stack, in this 
case 1234. In this way, quans act like constants. BINGO above also compiles to 
only 2 bytes instead of the 4 required to fetch if it were a variable (i.e., 
BINGO @). 

Getting the address of the data in the quan: 

AT BINGO 

This will leave the address of the first byte of data in BINGO on the 
stack, or compile the address as a literal if encountered during compilation. 

(AT is immediate.) This is useful for a variety of purposes in genera] 
programming and in interfacing to machine language routines. 


Advanced users: 

The FORTH 83 Standard appears to lean toward "non-state-smart" words, which 
is proper for target-compiled applications. We expect to support both "state- 
smart" and "non-state 1 smart" versions of various words, as appropriate for 
different users. 

Note that while 

15 AT BINGO +! and 15 BINGO + TO BINGO 

accomplish the same task and take the same amount of memory, the first version 
is faster by one primitive nest. 


The most significant internal feature of quan is that it has 3 cfa's instead of 
just the one common to most FORTH words. This initial 4 byte disadvantage is 

^ overcome at the second use of a quan, and so poses essentially no problem. 

CQUAN, 2QUAN, 3QUAN, etc., have also been implemented, and the user may have 
some fun puzzling these out before they are published elsewhere. Note that a 
2quan takes 2 arguments from the stack when used with TO, and leaves 2 when 
used alone. When used with AT, a 2quan still leaves the address of the first 

byte of its "parameter field," as does QUAN, Also, when defining CQUAN it is 

probably a good idea to still allot 2 bytes for data, so that +! can be used 
without fear of negative stack arguments. Another new defining structure is 
called "FLAG." Flags have only two cfa's, dropping the one that supports the 
"AT" function. Flags keep only one byte of data, a flag; hence they are 3 
bytes shorter than quans. Flags would not be used in this package enough to 
justify the additional code, but may be worthwhile in other applications. 

Higher speed and cleaner array structures may also be implemented using 
the quan strategy, and may be included in a future release of our utilities- 
editor package, (This would be made available to current u/e owners at a 
price-difference-plus-handl ing charge.) 

The word VECT has also been introduced in this package. It has two cfa's, and 
replaces the rather cumbersome variable-based vectoring procedure, 

' SQMEWORD CFA SQMEVARIABLE 1 and 

SOMEVARIABLE @ EXECUTE 

with the cleaner, faster, and memory-shorter 

' SQMEWORD CFA TO SOMEVECT and 
SOMEVECT 
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QUICK TRIG 


Since floating point trigonometric operations on the Atari machines are 
rather slow and provide accuracy unnecessary for many applications, this package 
provides integer versions of sine, cosine, and arctangent functions that run 
much faster than their floating point cousins. 

QSIN and QCOS expect scaled radian arguments in the range +-31416, (+-pi), 
with 10000 representing one radian. 

Similarly, QATN returns scaled radian arguments in range +-15708 (+-pi/2). 
QATN accepts arguments in the full single number range, again interpreting 10000 
as 1. This at first glance seems to be a significant limitation on QATN's input 
range but is circumvented by the existence of the more useful QATN2. QATN2 is 
a four-quadrant arctangent function. It accepts two stack arguments, which 
may be thought of as "'del ta--x" and "delta-y," and uses these arguments to 
construct a value to be used by QATN. QATN2 then performs sign corrections as 
necessary and returns a value in the range +-31416, QATN2 is what is actually 
used in graphics work, and is used in the word TURNTWD ("turn toward") elsewhere 
in this package. 

For user convenience, the words ->QRD and ->QDG are used to convert from 
scaled-degree arguments to scaled radian arguments and back again. 


16 K/ ( d - n ) 

This is a special-purpose high-speed routine that may find other uses. 
It divides a double number by 16384 and leaves a single number result. 
Used to speed quick-trig functions. 

QSIN { scaled-radians — scaled-sine ) 

Takes a scaled-radian argument ( range +-31416 ) and leaves the scaled 
sine in the range +-10000. 

QCOS ( scaled-radians -- scaled-cosine ) 

Takes a scaled-radian argument ( range +-31416 ) and leaves the scaled 
cosine in the range +-10000. 

QATN ( scaled-argument -- scaled-radians ) 

Takes a scaled-argument ( range 0 to 10000 ) and leaves the scaled 
arctangent in the range +-15708 (+-pi/2, scaled). 

QATN2 ( "delta-x" "delta-y" -- scaled-radians ) 

Assuming that the "x" axis points toward zero radians (zero degrees) 
on one end and pi radians (180 degrees) on the other, QATN2 leaves the 
angle ( range +-31416 ) between a line from the origin to the point 
( delta-x, delta-y ). 
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Counterclockwise angles are positive. 


+15708 



0 radians 




In the illustration above, arctan2 of { delta-x, delta-y ) would be 
approximately -2.1 radians, or -21000 as computed by QATN2. 

->QRD ( scaled-degrees — scaled-radians ) 

Takes a scaled-degree argument ( range +-18000 ) and converts it 
to a scaled-radian argument ( range +- 31416 ). 

~>QDG ( scaled radians — scaled-degrees ) 

Takes a scaled-radian argument ( range +-31416 ) and converts it 
to a scaled-degree argument. ( range +-18000). 
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FLOATING POINT EXTENSIONS, INCLUDING TRIG FUNCTIONS 


This section contains extensions to the Floating Point package provided 
with valFORTH 1.1. Source Code is on the valGraphics disk. The pages have been 
numbered so that it may be separated from the rest of the Turtle Graphics package 
and integrated into the original Floating Point package for ease of reference. 
Note that the trigonometric functions expect their arguments in radians, as is 
normal in floating point. Conversion words D6->RD and RD->DG have been provided 
for convenience, however. 

GLOSSARY 

PI, PI/2, PI/3, PI/4, and PI/6 (— fp ) 

leave their normal floating point values on the stack. 

EXP1 ( - fp ) 

leaves the value of the constant "e" on the stack. Though this name 
is slightly obscure, it was selected to avoid name collisions. 

FPO and FP1 ( — fp ) 

have been defined as FP 0 and FP 1, respectively, to reduce memory 
requirements. 

RD/DG and DG/RD { — fp } 

are constants equal to the number of radians in a degree and the 

number of degrees in a radian, respectively. 

FTOP and FBOT ( — fp ) 

are, approximately, the largest and smallest non-zero absolute 
values that the machine can represent. 

FMINUS ( fpl — fp2 ) 

Leaves the negative of fpl as fp2. 

2FDUP ( fpl fp2 — fpl fp2 fpl fp2 ) 

Duplicates the two fp values on the top of stack. 

F+! ( fpl addr — ) 

Add fpl to the fp value at address addr, and leaves result 
at addr. 

FMAX ( fpl fp2 — fp3 ) 

Leaves the maximum of fpl and fp2 as fp3. 
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FMIN ( fpl fp2 — fp3 ) 

Leaves the minimum of fpl and fp2 as fp3. 

F0< ( fpl — flag ) 

Leaves a true flag if fpl is negative; otherwise, leaves a 
false flag. 

FABS ( fpl - f P 2 ) 

Leaves the absolute value of fpl as fp2. 

2FDR0P ( fpl fp2 - ) 

Discards the two floating point numbers on top of stack. 

F, ( fpl - ) 

Compiles the floating point number on top of stack into the 
dictionary. 

F>R ( fpl - ) 

Sends fpl to the return stack. 

FR> ( - fpl ) ^ 

Retrieves the top 6 bytes of the return stack as fpl. 

FR ( - fpl) 

Copies the top 6 bytes of the return stack as fpl. 

F.S ( — ) 

Does a non-destructive printout of the stack assuming all 
fp numbers. 

FRICK ( fpn...fpl n — fpn..fpl fpn ) 

Copies the nth fp number to top of stack. Note that 1 FRICK 
is the same as FOUR and 2 FRICK is the same as FOVER. 

FROLL ( fpn fpn-l..fpl n — fpn-l..fpl fpn ) 

Pulls the nth fp number out of the stack and moves it to' top of 
stack. Note that 2 FROLL is the same as FSWAP and 3 FROLL would be 
the same as FROT. 

-FIX ( fpl — n ) 

Converts a fp number to a single number. Accepts positive or ^ 

negative fp. For large fp numbers, represents to most positive 
or most negative n, as appropriate. 
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- FLOAT ( n — fpl ) 

Converts a single number to a fp number. Accepts positive or 
negative values for n. 

F*0V ( fpl fp2 — fp3 ) 

Multiplies fpl and fp2 to produce fp3. If fp3 would overflow or 
underflow, leaves +~ greatest fp number or fp 0 as required. 

F/OV ( fpl fp2 - fp3 ) 

Divides fpl by fp2 to produce fp3. If fp3 would overflow or underflow, 
leaves +- greatest fp number or fp 0 as required. 

1/FP ( fpl — fp2 } 

Leaves the inverse of fpl as fp2, using F/OV. 

->RD ( degrees — radians ) 

Converts the.argument “degrees" into radians. "To radians." 

->D6 ( radians -- degrees ) 

Converts the argument "radians" into degrees. "To degrees." 

SIN ( fpl — fp2 ) 

Leaves the sine of fpl as fp2. 

COS ( fpl — fp2 ) . 

Leaves the cosine of fpl as fp2. 

TAN ( fpl — fp2 ) 

Leaves the tangent of fpl as fp2. 

(NOTE: SIN, COS, and TAN expansions fail for fpl above 
approximately 2E5 (200,000) radians or 1E7 (10,000,000) degrees.) 

ATN ( fpl — fp2 ) 

Leaves the arctangent of fpl as fp2. 

ATN2 { fpx fpy — fpl ) 

Leaves the four-quadrant arctangent of fpx and fpy as fpl. 

Assuming that the "x" axis points toward zero radians (zero degrees) 
on one end and pi radians (180 degrees) on the other, ATN2 leaves 
the angle, in radians, between a line from the origin to the point 
( fpx, fpy ). 
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Counterclockwise angles are positive. 


+1.5708 



In the illustration above, ATM2 of ( fpx, fpy ) would be approximately 
-2.1 radians. 


Reference: 

Software Manual for the Elementary Functions by William J 0 Cody, Jr. 
and William Waite. 
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General 

Functions 


PEN 

( n -- ) 

This command is used to change the color with 
which the armadillo draws and fills. 

PHPEN 

( n — ) 

This command is used to change the color with 
which the armadillo fills. 

DRAW 

( n — ) 

Move the armadillo n units in the direction 
in which it is heading. Draw that portion of 
the line of travel of the armadillo that falls 
within the current window. 

DRAWTO 

( x y -- ) 

Move the armadillo to x y and draw that portion 
of the line of travel that falls within the 
current window. 

PHIL 

( n — ) 

Move the armadillo n spaces in the direction 
it is heading, and color that portion of the 
path of travel with the PEN value. Also 
perform a fill to the right during che time 
that the armadillo is in the current window. 

PHILTG 

( x y - ) 

Move the armadillo to the point x, y: Then 
proceed as in PHIL. 

GO 

in—) 

GO moves the armadillo n units in the direction 
in which it is facing. 

DUPGO 

( n — n ) 

Same as GO, but doesn't destroy stack argument. 

GO. 

fn — ) 

Same as GO, but colors last pixel with PEN color. 

DUPGO. 

( n — n ) 

Same as GO., but doesn't destroy stack argument. 

DOT 

; - s 

DOT puts a pen-color dot at the present 
armadillo position. 

GOTO 

( x y - i 

GOTO positions the armadillo at x,y. 

GOTO. 

(>)•*) 

Same as GOTO but puts dot at x,y. 

CENTER 


Positions the armadillo at the point 0,0. 

CENTERO 

! - ) 

Positions the armadillo at the point 0,0 and 
turns it to face up. 

RELOC 

( - ) 

Positions the armadillo at the last point 
drawn by the system routines. DILLO vocab. 

ASPECT 

( ON or OFF -- ) 

ON ASPECT will cause vertical components of 
subsequent graphics commands to be scaled to 
account for pixels not being square. 

DX1 

( — n ) 

Returns the x coordinate of the armadillo. 

DY1 

( - n ) 

Returns the y coordinate of the armadillo. 

TURN 

( n - ) 

Changes the direction that the armadillo is 
facing by n degrees clockwise. 

TURNTO 

( n — ) 

Turns the armadillo to a heading of n degrees 
clockwise from vertical. 

TURNTWD 

( x y — ) 

Turns the armadillo so that it faces toward 
the point x,y. 

DAZM 

( -- n ) 

Returns the direction, in degrees (0-359), in 
which the armadillo is facing. 

Windows and Coordinate Systems 

WINDOW 

( left right 

top bottom — ) 

Sets a new window whose boundaries, expressed 
in the coordinate system of the base window 
(not the current window), are taken from the 
stack in the order indicated. 

RELWND 

( left right 

top bottom — ) 

Makes current a window whose edges are as 
indicated on stack in the coordinate system 
cf the current window (not the base window). 

WIPE 

( - ) 

Colors the entire current window according to 
the color register selected by the last PHBAK 
command, but uses DRAW and draw options. 

FRAME 

( -- ) 

Draws a line around the current window. 

BASWND 

( - ) 

Makes the base window (usually the full window 
first put up by a GR. command) current, centers 
the armadillo and turns it to 0 degrees. 

THISWND 

XXX, ( -- ) 

xxx: { — ) 

Creates a word, xxx, which when executed makes 
current the window which was current at the 
time xxx was defined. 

DEFBAS 

{ left right 

top bottom -- ) 

Advanced users. Used to set up a base window 
when not using GR.. The values indicated are 
the number of pixels from the left edge of the 
display (for left and right) and from the top 
edge of the display (for top and bottom). DILLO. 

WCTR 

( - ) 

Center the armadillo in the current window. 

WCTRO 

( - ) 

Center the armadillo in the current window and 
turn it to 0 degrees. 


Line-naming/Line Manipulation and Point-naming 


NAMEPT 

xxx, 

( X y — ) 

Creates a word xxx. When xxx is executed, it 


xxx: 

( - x y ) 

returns x and y to the stack. 

THISPT 

xxx. 

<— -) 

Creates a word xxx. xxx returns defining-time 


xxx: 

( — x y ) 

armadillo x,y. 

2PT-LN 

( xl 

yl x2 y2 ~ a b c ) 

Takes the coordinates of two points and leaves 
a, b, and c of the connecting line. 

MAKLN 

( - 

a b c ; 

Pushes to stack the a, b, c representation of 
the imaginary line along which the armadillo 
faces. 

NAMELN 

xxx. 

( a b c -- ] 

Creates the word xxx. When xxx is executed. 


xxx: 

( — a b c ) 

it returns the values a b c to the stack. 

THISLN 

xxx, 

( - ) 

Creates the word xxx. When xxx is executed. 


xxx: 

; a b c ) 

it returns the a, b, and c values of the line 
that the armadillo was sitting on and facing 
along when xxx was created. 

2LNX 

( al 

bl cl a2 b2 c2 
— x y ! 

Given two lines on the stack in a b c form, 
2LNX returns the point of intersection of the 
two 1ines. 


Options 

(All words below take a flag stack argument, and leave none.) 
ON 


Switch 

Defaul 

RPHIL 

on 

LPHIL 

off 

DRXOR 

off 

PHXOR 

off 

DRUNT 

off 

PHUNT 

off 

DRUNOT 

on 

PHUNOT 

on 

PH+DR 

on 

DR1ST 

on 

PHCRNR 

off 


Enables right fill 
with PHIL, PHILTO 
Enables left fill 
with PHIL, PHILTO. 
DRAW, DRAWTO will 
xor pixels with 
1ine color. 

PHIL, PHILTO will 
xor pixels with 
fill color. 

Enable draw-until 
functions. 

Fill to edge of 
window or to dest. 
pixel. 

With DRUNT on, 

DRAW, DRAWTO draw 
until hit color set 
by DRBAK, PHBAK. 

With PHUNT on, 

PHIL, PHILTO fill 
until hitting color 
set by PHBAK. 

PHIL, PHILTO draw 
line as filling. 
First point of 
lines is drawn. 

PHIL, PHILTO perform 
corner checking, 
armadillo must be 
moving vertically. 


OFF 

Disables right fill 
with PHIL, PHILTO. 
Disables left fill 
with PHIL, PHILTO. 
DRAW, DRAWTO will 
replace pxls with 
line color. 

PHIL, PHILTO will 
replace pxls with 
fill color. 

Disable draw-until 
functions. 

Fill until encounter¬ 
ing halt pixel cond 
set by PHBAK, PHUNOT. 
With DRUNT on, 

DRAW, DRAWTO draw 
until hit not color 
set by DRBAK, PHBAK. 
With PHUNT on, 

PHIL, PHILTO fill 
until hitting not 
color set by PHBAK. 
PHIL, PHILTO don't 
draw line as filling. 
First point of 1 ines 
is not drawn. 

No corner checking. 


DINIT sets all switches to their default values. 
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